import 'dart:async';
import 'package:flutter/widgets.dart';

/// [AutoRefreshMixin]：通用的 **自动刷新 Mixin**，可混入到 [State] 中使用。
///
/// 功能：
/// - 提供一个 [refreshInterval]，定义自动刷新的时间间隔；
/// - 内部通过 [Timer.periodic] 定时触发 [onAutoRefresh]；
/// - 在 [dispose] 时自动清理定时器，避免内存泄漏。
///
/// 使用场景：
/// - 需要定时更新的组件，例如：
///   - 实时数据展示（倒计时、时钟、行情面板）；
///   - 自动轮询（状态检查、消息刷新）；
///   - 周期性 UI 更新（动画、闪烁效果）。
///
/// 使用示例：
/// ```dart
/// class MyWidget extends StatefulWidget {
///   @override
///   _MyWidgetState createState() => _MyWidgetState();
/// }
///
/// class _MyWidgetState extends State<MyWidget> with AutoRefreshMixin<MyWidget> {
///   @override
///   Duration get refreshInterval => const Duration(seconds: 1);
///
///   @override
///   void onAutoRefresh() {
///     setState(() {
///       // 定时刷新逻辑，例如更新时间
///     });
///   }
///
///   @override
///   Widget build(BuildContext context) {
///     return Text(DateTime.now().toIso8601String());
///   }
/// }
/// ```
mixin AutoRefreshMixin<T extends StatefulWidget> on State<T> {
  Timer? _autoRefreshTimer;

  /// 刷新间隔（子类必须实现）。
  ///
  /// 示例：`const Duration(seconds: 1)`
  Duration get refreshInterval;

  /// 定时触发的刷新逻辑（子类必须实现）。
  ///
  /// - 在每个 [refreshInterval] 到期时调用；
  /// - 通常需要调用 [setState] 以触发界面刷新。
  void onAutoRefresh();

  @override
  void initState() {
    super.initState();
    _autoRefreshTimer =
        Timer.periodic(refreshInterval, (_) => onAutoRefresh());
  }

  @override
  void dispose() {
    _autoRefreshTimer?.cancel();
    super.dispose();
  }
}
